---
title: Vectors
slug: /vector
section: Math
---

Excalibur uses the [[Vector]] structure to represent points. The [[Vector]] class has many different static methods available for doing vector math as well as instance methods to combine vectors together in different ways.

## Creating vectors

To quickly create a vector, use the [[vec]] global:

```ts twoslash
import { vec } from 'excalibur'

const point = vec(0, 10)
```

Alternatively, you may see examples of using the more verbose `new Vector(x, y)` format:

```ts twoslash
import { Vector } from 'excalibur'

const point = new Vector(0, 10)
```

To set the value of an existing vector, use [[Vector.setTo]]:

```ts twoslash
import { vec } from 'excalibur'

const point = vec(0, 10).setTo(10, 10)
```

There are some built-in vector constants you can use:

- [[Vector.Zero]]
- [[Vector.One]]
- [[Vector.Half]]
- [[Vector.Left]]
- [[Vector.Right]]
- [[Vector.Up]]
- [[Vector.Down]]

## Cloning vectors

Vectors are objects, so mutating them will change the state for all references. Use the [[Vector.clone]] method to clone a vector to mutate it:

```ts twoslash
import { vec } from 'excalibur'

const point = vec(0, 10)
point.setTo(8, 8)
     // ^?
const samePoint = point
const anotherPoint = point.clone()
anotherPoint.setTo(50, 50)

console.log(point.toString()) // "(8, 8)"
console.log(samePoint.toString()) // "(8, 8)"
console.log(anotherPoint.toString()) // "(50, 50)"
```


:::tip

Notice how both `point` and `samePoint` share the same vector reference, so using `setTo` mutates the vector. Use `clone` to ensure you are not changing vectors unexpectedly!

`setTo` returns `void` so that it "feels awkward" to chain it. 
This is intentional to avoid confusion about whether you are mutating the vector or creating a new one. 

:::

## Linear interpolation (lerp) between vectors

[[Vector.lerp|Lerp]] returns a new vector that represents a point along the line between two vectors. Given a number between 0 and 1 (representing the percentage of progress) and a target vector, it produces the intermediate vector at that fraction of the distance.

The standard formula for linear interpolation is:

```
lerp(a, b, t) = a + (b - a) * t
```

- a = starting vector
- b = target vector
- t = interpolation factor (0 ≤ t ≤ 1)

When t = 0, the result is a.

When t = 1, the result is b.

When t = 0.5, the result is exactly halfway between a and b.
